Inside Macintosh: Telephony /

Chapter 4 - Call Appearances / Call Appearance Reference

Data Structures

Call Appearance Structure

The call appearance structure stores all available information about a call appearance. The Telephone Manager allocates the memory for and creates all call appearance structures. Telephone tools provide the values for most of the structure fields.

The Telephone Manager provides your application with handles to call appearance structures. You get a handle to a new call appearance structure for an outgoing call when

• you call the TELSetupCall function (page 4-24)
• your call appearance message handler gets a telCAOutgoingMsg message because a user manually initiated a call

Note

You'll also get a telCAOutgoingMsg message containing a new handle to a call appearance structure if another Telephone Manager client initiates a call. The Telephone Manager sends an identical message to all registered message handlers that want to receive a given type of call appearance message.

You get a handle to a new call appearance structure for an incoming call when your call appearance message handler gets any of the following messages:

• telCAAlertingMsg
• telCAOfferMsg
• telCAQueuedMsg

You are responsible for disposing of a handle to a call appearance structure that belongs to your application when you have no further need for the structure.

A call appearance structure is like a snapshot--it describes the characteristics and state of a call at the time the structure is created or at the most recent update. You can cause a call appearance structure to be updated by calling the TELGetCAInfo (page 4-54), TELGetCAState (page 4-54), and TELGetCAFlags (page 4-55) functions.

IMPORTANT

You can change values only in the refCon, userData, and connectTime fields. To be compatible with future releases of the Telephone Manager, do not directly manipulate any other fields of a call appearance structure. Telephone tools and the Telephone Manager provide and maintain the values for all other fields.

The call appearance structure is defined by the TELCARecord data type.

struct TELCARecord {
   short                   caRef;
   TELDNHandle             hTELDN;
   TELHandle               hTEL;
   short                   caState;
   TELCAHandle             relatedCA;
   long                    connectTime;
   short                   intExt;
   short                   callType;
   short                   dialType;
   short                   bearerType;
   short                   rate;
   StringPtr               rmtDN;
   StringPtr               rmtPartyName;
   StringPtr               rmtSubaddress;
   StringPtr               routeDN;
   StringPtr               routePartyName;
   StringPtr               routeSubaddress;
   short                   priority;
   short                   conferenceLimit;
   TELCAFeatureFlags       featureFlags;
   TELCAOtherFeatures      otherFeatures;
   long                    telCAPrivate;
   long                    refCon;
   long                    userData;
   long                    reserved;
};
typedef struct TELCARecord TELCARecord;
typedef TELCARecord *TELCAPtr, **TELCAHandle;

Field Description

caRef

A call appearance reference number. A telephone tool dynamically generates this value to identify a particular call appearance.

hTELDN

A handle to the structure for the local directory number to which this call appearance belongs. The Telephone Manager supplies this value.

hTEL

A handle to the telephone structure for the directory number specified through the hTELDN parameter. The Telephone Manager supplies this value.

caState

A constant that indicates the state of the call. See "Call Appearance States" (page 4-10) for a description of call appearance states. A telephone tool provides this value.

relatedCA

A handle to a call appearance structure with which this call appearance is associated, such as in a conference call or a transfer. The Telephone Manager supplies this value. If there is no associated call appearance, this field contains nil.

connectTime

Reserved for your use. For instance, you can use it to store a timestamp indicating when a connection was attempted or completed. Or, you can use it to store the duration of a call. You are responsible for maintaining this field if used by your application.

intExt

Information about where the call originates relative to the local switch or closed user group. See "Call Origination Types" (page 4-13) for a description of the constants that can occur in this field. A telephone tool provides this value.

callType

Indicates the way in which the call reached or left this terminal--for instance, whether it was transferred or forwarded. The constants that define call types are described in "Call Types" (page 4-11). A telephone tool provides this value.

dialType

Indicates the dialability and the format of the remote directory number. The constants that define dial types are described in "Dial Types" (page 4-14). A telephone tool provides this value.

bearerType

Reserved. A telephone tool always sets this to 0.

rate

Reserved. A telephone tool always sets this to 0.

rmtDN

A pointer to a Pascal-style string containing the remote telephone number associated with this call. A telephone tool provides this value for an incoming call. For an outgoing call, if your application passed the remote telephone number to the TELSetupCall function (page 4-24), the Telephone Manager sets this field accordingly. If the remote telephone number is unknown, this field contains nil.

rmtPartyName

A pointer to a Pascal-style string containing the name of the remote party associated with the remote telephone number. A telephone tool provides this value for incoming calls. For outgoing calls, a tool or your application may provide the remote party name, depending on the implementation. If the name is unknown, this field contains nil.

rmtSubaddress

A pointer to the network subaddress of the remote telephone number. A telephone tool provides this value for an incoming call. For an outgoing call, if your application passed the subaddress to the TELSetupCall function (page 4-24), the Telephone Manager sets this field accordingly. If there is no subaddress, this field contains nil.

routeDN

A pointer to a Pascal-style string containing the telephone number through which this incoming call was routed. If the call was not routed or if the routing telephone number is unknown, this field contains nil. A telephone tool provides this value.

routePartyName

A pointer to a Pascal-style string containing the name of the party associated with the routing telephone number. If the name of the party is unknown, this field contains nil. A telephone tool provides this value.

routeSubaddress

A pointer to the network subaddress of the routing telephone number. If there is no subaddress, this field contains nil. A telephone tool provides this value.

priority

Reserved.

conferenceLimit

The maximum number of parties that can be concurrently conferenced with this call appearance. The maximum includes the two parties initially associated with the call appearance. If there is no limit on the number of calls that can be conferenced, this field contains 0. A telephone tool provides this value.

featureFlags

A bit field that indicates certain features of this call appearance and the state of each feature (subscribed, available, or active). The constants that define the bits are described in "Call Appearance Feature Flags" (page 4-15). A telephone tool provides this value.

otherFeatures

A bit field that indicates additional features of this call appearance and the state of each feature (subscribed, available, or active). The constants that define the bits are described in "Other Call Appearance Feature Flags" (page 4-17). A telephone tool provides this value.

telCAPrivate

Reserved for telephone tools.

refCon

Reserved for your use.

userData

Reserved for your use.

reserved

Reserved.